 /*______________________________________________________________________________
 *
 * Copyright 2005 NORSYS
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * (1) Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *
 * (2) Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in
 *     the documentation and/or other materials provided with the
 *     distribution.
 *
 * (3) The name of the author may not be used to endorse or promote
 *     products derived from this software without specific prior
 *     written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 *______________________________________________________________________________
 *
 * Created on 26 sept. 2005
 * Author: Arnaud Bailly
 */
package speculoos.spi;

import java.util.Map;

import speculoos.core.Mapper;
import speculoos.core.MapperException;


/**
 * An interface that is implemented by data sources provider 
 * and used by mappers managers.
 * A source is responsible for the management of resources associated
 * with a mapper such that connections, credentials, sessions, caches, ...
 * To allow proper life-cycle handling, methods {@link #start(java.util.Map)} and {@link #stop()}
 * are provided: 
 * <ul>
 * <li>Method start is called by the manager of the Source object when it
 * is itself started. This method is passed an environment which is a map 
 * from strings to objects. The Source may do what it wants with the map
 * itself but must <strong>not</strong> modify the objects stored inside.</li>
 * <li>Method stop is called by the manager of the Source object when 
 * is stopped.</li>
 * <li>Method <code>create</code> is called when a client of the manager 
 * wants to retrieve a mapper object associated with this source, giving the opportunity 
 * to the source object to prepare resources for the mapper  </li>
 * <li>Method <code>release</code> is called when the client no longer needs
 * the mapper. </li>
 * </ul>
 * 
 * @author nono
 * @version $Id: Source.java 259 2006-05-23 10:34:50Z /C=FR/ST=Nord/L=Lille/O=Norsys SA/OU=UE/CN=Arnaud Bailly/emailAddress=abailly@norsys.fr $
 * 
 */
public interface Source {

	/**
	 * Returns the name associated with this source.
	 * 
	 * @return a string identifier for this source.
	 */
	String getName();
	
    /**
     * Called when the component manager is ready to operate.
     * 
     * @param env the environment to use for this "session".
     * @throws MapperException if something prevents the 
     * source from starting its operations.
     */
    public void start(Map env) throws MapperException;
    
    /**
     * Called when the component manager stops operating.
     * 
     *
     */
    public void stop();
    
    /**
     * Called before the mapper is handled to the client.
     * 
     * @param m the mapper to prepare
     * @param environment the environment to use. The source object
     * must not modify the passed environment.
     * @return a Mapper object corresponding to given name and 
     * initialized with given environmnet
     * @throws MapperException
     */
    Mapper create(String m, Map environment) throws MapperException;

    /**
     * Called when the mapper is released.
     * <p>
     * This method is called either by direct speculoos.manager.Manage#release(Mapper) 
     * invocation from client or by indirect cleanup from 
     * the manager.
     * </p>
     * <p>
     * This method <strong>must</strong> be idempotent: Successive invocation 
     * with the same mapper should be OK. 
     * </p>
     * @param mapper the mapper to release
     */
    void release(Mapper mapper)throws MapperException;

    /**
     * Allows configuration process to define variables within the scope
     * of a single source. 
     * <p>
     * The <code>params</code> map's values may contains references to other
     * variables in the form <code>${nom_variable}</code> but it is up
     * to the implementation to make sure that these references will
     * be instantiated after startup.
     * </p>
     * <p>
     * This method may not be invoked after method {@link #start(Map)} has been
     * invoked but it may be called several times: old values should be 
     * replaced by new values in map.
     * </p>
     * @param params a Map<String,String> object. May not be null.
     */
    void addParameters(Map params);
}
